feat(web): Agent Inbox UI — the Claude Design hand-back over the real API (HT-23) - #32

web/src/app/inbox/[folder]/page.tsx (1)

6-6: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Derive folder allowlist from the shared type instead of duplicating it.

FOLDERS re-declares the same three literals as ConversationFolder in api-types.ts, and a third copy exists in InboxScreen.tsx's FOLDERS array. If a new folder is ever added to the type, this Set is easy to forget, silently 404ing a valid folder.

♻️ Suggested fix

-const FOLDERS: ReadonlySet<string> = new Set(['open', 'closed', 'spam'])
+// api-types.ts
+export const CONVERSATION_FOLDERS = ['open', 'closed', 'spam'] as const
+export type ConversationFolder = (typeof CONVERSATION_FOLDERS)[number]

Then here:

-const FOLDERS: ReadonlySet<string> = new Set(['open', 'closed', 'spam'])
+import { CONVERSATION_FOLDERS } from '../../../lib/api-types'
+const FOLDERS: ReadonlySet<string> = new Set(CONVERSATION_FOLDERS)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/app/inbox/`[folder]/page.tsx at line 6, Update the folder validation
in FOLDERS to derive its allowed values from the shared ConversationFolder type
in api-types.ts rather than duplicating the string literals. Reuse the shared
type or its existing runtime representation, and preserve the current open,
closed, and spam behavior.

web/src/components/ds/core/IconButton.jsx (1)

39-44: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Imperative DOM style mutation on hover bypasses React reconciliation.

Mutating e.currentTarget.style.background directly in onMouseEnter/onMouseLeave works today, but if active/tone change while the pointer is still hovering, the imperative mutation could go stale until the next render forces a full style recalculation. A CSS :hover rule (or hover state via useState) would keep visuals in sync with props consistently.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/core/IconButton.jsx` around lines 39 - 44, Replace the
imperative background mutations in IconButton’s onMouseEnter and onMouseLeave
handlers with a React-controlled hover state or CSS :hover styling. Ensure the
rendered background stays synchronized with active and tone/hoverBg prop changes
while the pointer remains over the button, preserving the existing active and
transparent non-hover appearance.

web/src/components/ds/core/DropdownMenu.jsx (1)

13-35: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider Escape-key dismissal for a11y.

The dropdown closes on backdrop click but has no keyboard (Escape) handling, which is a common expectation for menu/dropdown patterns. Given this is a shared design-system primitive used across the inbox UI, adding an Escape handler would improve keyboard accessibility.

♻️ Suggested addition

+import React, { useEffect } from 'react'
+
 export function DropdownMenu({
   open,
   onClose,
   align = 'left',
   top = 36,
   minWidth = 160,
   children,
 }) {
+  useEffect(() => {
+    if (!open) return
+    const onKeyDown = (e) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', onKeyDown)
+    return () => document.removeEventListener('keydown', onKeyDown)
+  }, [open, onClose])
+
   if (!open) return null

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/core/DropdownMenu.jsx` around lines 13 - 35, The
DropdownMenu component only dismisses through backdrop clicks and needs keyboard
dismissal. Add an Escape-key listener while the menu is open that invokes
onClose, clean it up when closed or unmounted, and preserve the existing
backdrop and rendering behavior.

web/src/components/ds/core/Skeleton.jsx (1)

4-20: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Duplicate <style> injection and missing a11y hint.

Two things worth addressing:

• Each Skeleton instance injects its own <style> tag with the same @keyframes ht-pulse rule. If several skeletons render at once (list loading states), this duplicates the same CSS block many times in the DOM.
• The placeholder has no aria-hidden="true", so it may be announced as meaningless content by screen readers.

♻️ Proposed fix

 export function Skeleton({ width = '100%', height = 12, radius = 4, style }) {
   return (
-    <>
-      <style>{'`@keyframes` ht-pulse{0%,100%{opacity:1}50%{opacity:.45}}'}</style>
-      <div
+    <div
+        aria-hidden="true"
         style={{
           width,
           height,
           borderRadius: radius,
           background: 'var(--ht-surface-2)',
           animation: 'ht-pulse 1.5s ease-in-out infinite',
           ...style,
         }}
-      />
-    </>
+    />
   )
 }

Move the @keyframes ht-pulse definition into the theme CSS (e.g. web/src/theme/helpthread.css) once, instead of per-instance.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/core/Skeleton.jsx` around lines 4 - 20, Remove the
per-instance style injection from Skeleton and define the ht-pulse keyframes
once in the shared theme CSS. Add aria-hidden="true" to the Skeleton placeholder
div while preserving its existing styling and animation behavior.

web/src/components/ds/core/TextInput.d.ts (1)

1-9: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Replace any event types with proper React event types.

@types/react is already a project dependency; use it for stronger typing instead of any, which defeats the purpose of this .d.ts contract.

♻️ Proposed fix

 export interface TextInputProps {
   value?: string
-  onChange?: (e: any) => void
-  onKeyDown?: (e: any) => void
+  onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void
+  onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>) => void
   placeholder?: string
   id?: string
   style?: React.CSSProperties
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/core/TextInput.d.ts` around lines 1 - 9, Update the
TextInputProps onChange and onKeyDown callbacks to use the appropriate React
event types from `@types/react` instead of any, preserving their existing callback
semantics and the rest of the TextInput declaration.

web/src/components/ds/core/MenuItem.jsx (1)

14-41: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Expose selected state to assistive tech.

The visual selected state (line 12, 27) isn't communicated via ARIA. Since this is used as a dropdown menu row, consider adding role="menuitem" and aria-selected={selected} so screen reader users get the same signal as sighted users.

♿ Proposed fix

     <button
       type="button"
+      role="menuitem"
+      aria-selected={selected}
       onClick={onClick}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/core/MenuItem.jsx` around lines 14 - 41, Update the
MenuItem button to expose its selection state to assistive technology by adding
role="menuitem" and binding aria-selected to the existing selected prop. Keep
the current visual styling and click behavior unchanged.

web/src/components/ds/core/TagChip.jsx (1)

21-51: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add aria-label to the icon-only remove button.

title alone isn't a reliable accessible name for icon-only buttons across assistive technologies.

♿ Proposed fix

         <button
           type="button"
           title="Remove tag"
+          aria-label="Remove tag"
           onClick={onRemove}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/core/TagChip.jsx` around lines 21 - 51, Add an explicit
aria-label describing the remove action to the icon-only button in TagChip,
alongside the existing title and onClick behavior. Keep the label specific to
removing the tag.

web/src/components/ds/core/StatusPill.d.ts (1)

1-8: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider a union type for status instead of string.

The comment documents a fixed set of known statuses matching the META map in StatusPill.jsx, but the type allows any string, so typos won't be caught at compile time.

♻️ Proposed fix

 export interface StatusPillProps {
-  /** active | pending | closed | spam | note (unknown = neutral) */
-  status: string
+  /** unknown values fall back to a neutral pill */
+  status: 'active' | 'pending' | 'closed' | 'spam' | 'note' | string
   /** override the derived label */
   label?: string
   style?: React.CSSProperties
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/core/StatusPill.d.ts` around lines 1 - 8, Update
StatusPillProps.status to a string-literal union containing the documented
statuses: active, pending, closed, spam, and note. Preserve the component’s
runtime handling of unknown values as neutral while enabling compile-time
detection of invalid status strings.

web/src/components/ds/inbox/MessageBand.d.ts (1)

7-8: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

delivery is typed as a plain string despite only two valid values.

The comment documents "sent" | "pending" as the only meaningful values, and the implementation (MessageBand.jsx) branches on delivery === 'pending'. A literal union would catch typos at compile time.

-  /** outbound only: "sent" | "pending" */
-  delivery?: string
+  /** outbound only */
+  delivery?: 'sent' | 'pending'

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/inbox/MessageBand.d.ts` around lines 7 - 8, Update the
delivery property type in the MessageBand declaration to the literal union of
"sent" and "pending", preserving its optionality so invalid delivery values are
rejected while omitted values remain valid.

web/src/components/ds/inbox/ConversationRow.d.ts (2)

17-17: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Avoid any for the checkbox change handler.

onCheck?: (e: any) => void discards type safety on the event object. Since the implementation wires this directly to a checkbox onChange, this should be typed against the concrete DOM event.

-  onCheck?: (e: any) => void
+  onCheck?: (e: React.ChangeEvent<HTMLInputElement>) => void

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/inbox/ConversationRow.d.ts` at line 17, Update the
onCheck callback type in ConversationRow’s declaration to use the concrete
checkbox change event type instead of any, matching the DOM event passed by the
checkbox onChange handler.

---

23-23: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

JSX.Element uses the deprecated global JSX namespace under React 19 types.

React 19's @types/react deprecates the global JSX namespace in favor of React.JSX. It still compiles today (deprecated alias, not removed), but new code should use React.JSX.Element to avoid editor/lint deprecation warnings and future breakage. Same pattern recurs in FolderItem.d.ts, MessageBand.d.ts, and ToolbarBand.d.ts.

-export declare function ConversationRow(props: ConversationRowProps): JSX.Element
+export declare function ConversationRow(props: ConversationRowProps): React.JSX.Element

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/inbox/ConversationRow.d.ts` at line 23, Update the
ConversationRow declaration return type from the deprecated global JSX.Element
to React.JSX.Element, adding or preserving the appropriate React type reference.
Apply the same return-type update to the corresponding declarations in
FolderItem.d.ts, MessageBand.d.ts, and ToolbarBand.d.ts.

web/src/components/ds/inbox/FolderItem.jsx (1)

12-37: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider exposing active state to assistive tech.

The button visually differentiates the active folder (bold, accent bg) but doesn't expose this via aria-current for screen reader users.

     <button
       type="button"
+      aria-current={active ? 'page' : undefined}
       onClick={onClick}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/inbox/FolderItem.jsx` around lines 12 - 37, Add an
aria-current attribute to the FolderItem button, using the existing active state
so the active folder is exposed to assistive technologies while inactive folders
remain unmarked.

web/src/components/ds/inbox/MessageBand.jsx (1)

97-103: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Decorative icon should be hidden from assistive tech.

The eye SVG conveys no information beyond the adjacent "Customer viewed …" text; it should be marked aria-hidden so screen readers don't announce a redundant/unlabeled graphic.

-            <svg width="12" height="12" viewBox="0 0 24 24">
+            <svg width="12" height="12" viewBox="0 0 24 24" aria-hidden="true">

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/components/ds/inbox/MessageBand.jsx` around lines 97 - 103, Update
the eye SVG in the viewed-status markup near the “Customer viewed” text to
include aria-hidden="true", keeping the adjacent text and icon styling
unchanged.

biome.json (1)

24-40: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Broad a11y rule suppression for the whole ds/** tree.

useKeyWithClickEvents and noStaticElementInteractions are disabled for every current and future file under web/src/components/ds/**, not just the ported hand-back components. This can silently hide real keyboard/interaction accessibility bugs in new components added later under this path.

Consider narrowing the override (e.g., per-file biome-ignore comments on the offending lines) or adding a tracking comment/issue to revisit and remove this override once the ported components are audited.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@biome.json` around lines 24 - 40, Narrow the biome.json override for
web/src/components/ds/** so useKeyWithClickEvents and
noStaticElementInteractions are not broadly disabled for current and future
components. Prefer targeted per-file or per-line ignores for the ported
components that require them; if the directory-wide override must remain, add a
tracking comment or issue reference documenting its removal after those
components are audited.

web/src/theme/fonts/fonts.css (1)

3-3: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Prefer next/font/google over a manual CSS @import.

A runtime @import from fonts.googleapis.com sends a request (and the user's IP) to Google on every page load, and doesn't get Next.js's automatic self-hosting, preloading, or layout-shift mitigation. Since this is a Next.js 15 app, next/font/google self-hosts the same fonts at build time with no external requests and better CLS behavior.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/src/theme/fonts/fonts.css` at line 3, Replace the manual Google Fonts
`@import` in fonts.css with Next.js 15's next/font/google integration, configuring
Source Serif 4 and Source Code Pro with the same styles, weights, and display
behavior. Apply the generated font variables or class names through the existing
app layout/theme entry point, and remove the external CSS import.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes